home *** CD-ROM | disk | FTP | other *** search
/ Mac-Source 1994 July / Mac-Source_July_1994.iso / Other Langs / Tickle-4.0 (tcl) / library / help / tcl / strings / scan < prev    next >
Encoding:
Text File  |  1993-10-26  |  5.8 KB  |  116 lines  |  [TEXT/$Tcl]
  1.  
  2.           scan string format varName ?varName ...?
  3.  
  4.  
  5.      INTRODUCTION
  6.           This command parses fields from an input string in the  same
  7.           fashion  as  the ANSI C sscanf procedure and returns a count
  8.           of the number of fields sucessfully  parsed.   String  gives
  9.           the input to be parsed and format indicates how to parse it,
  10.           using % conversion specifiers as in  sscanf.   Each  varName
  11.           gives  the  name of a variable; when a field is scanned from
  12.           string the result  is  converted  back  into  a  string  and
  13.           assigned to the corresponding variable.
  14.  
  15.  
  16.      DETAILS ON SCANNING
  17.           Scan operates by scanning string and formatString  together.
  18.           If the next character in formatString is a blank or tab then
  19.           it is ignored.  Otherwise, if it isn't a % character then it
  20.           must  match  the  next  non-white-space character of string.
  21.           When a % is encountered in formatString,  it  indicates  the
  22.           start  of  a  conversion  specifier.  A conversion specifier
  23.           contains three fields after the %: a *, which indicates that
  24.           the  converted  value is to be discarded instead of assigned
  25.           to a variable; a number indicating a  maximum  field  width;
  26.           and  a  conversion  character.   All  of  these  fields  are
  27.           optional except for the conversion character.
  28.  
  29.           When scan finds a conversion specifier in  formatString,  it
  30.           first  skips  any white-space characters in string.  Then it
  31.           converts the next input characters according to the  conver-
  32.           sion  specifier  and stores the result in the variable given
  33.           by the next argument  to  scan.   The  following  conversion
  34.           characters are supported:
  35.  
  36.           d         The input field must be a decimal integer.  It  is
  37.                     read in and the value is stored in the variable as
  38.                     a decimal string.
  39.  
  40.           o         The input field must be an octal  integer.  It  is
  41.                     read in and the value is stored in the variable as
  42.                     a decimal string.
  43.  
  44.           x         The input field must be a hexadecimal integer.  It
  45.                     is read in and the value is stored in the variable
  46.                     as a decimal string.
  47.  
  48.           c         A single character is read in and its binary value
  49.                     is  stored  in  the  variable as a decimal string.
  50.                     Initial white space is not skipped in  this  case,
  51.                     so the input field may be a white-space character.
  52.                     This conversion is different from the  ANSI  stan-
  53.                     dard  in that the input field always consists of a
  54.                     single character and no field width may be  speci-
  55.                     fied.
  56.  
  57.           s         The input field consists of all the characters  up
  58.                     to  the next white-space character; the characters
  59.                     are copied to the variable.
  60.  
  61.           e or f or g
  62.                     The input field must be  a  floating-point  number
  63.                     consisting  of  an  optional  sign,  a  string  of
  64.                     decimal digits  possibly  con  taining  a  decimal
  65.                     point, and an optional exponent consisting of an e
  66.                     or E followed by an optional sign and a string  of
  67.                     decimal  digits.   It is read in and stored in the
  68.                     variable as a floating-point string.
  69.  
  70.           [chars]   The input field consists of any number of  charac-
  71.                     ters  in  chars.  The matching string is stored in
  72.                     the variable.  If the first character between  the
  73.                     brackets  is  a  ]  then  it is treated as part of
  74.                     chars rather than the closing bracket for the set.
  75.  
  76.           [^chars]  The input field consists of any number of  charac-
  77.                     ters  not in chars.  The matching string is stored
  78.                     in the variable.   If  the  character  immediately
  79.                     following  the ^ is a ] then it is treated as part
  80.                     of the set rather than the closing bracket for the
  81.                     set.
  82.  
  83.           The number of characters read from the input for  a  conver-
  84.           sion is the largest number that makes sense for that partic-
  85.           ular conversion (e.g.  as many decimal  digits  as  possible
  86.           for %d, as many octal digits as possible for %o, and so on).
  87.           The input field for a  given  conversion  terminates  either
  88.           when a white-space character is encountered or when the max-
  89.           imum field width has been reached,  whichever  comes  first.
  90.           If  a * is present in the conversion specifier then no vari-
  91.           able is assigned and the next scan argument is not consumed.
  92.  
  93.  
  94.      DIFFERENCES FROM ANSI SSCANF
  95.           The behavior of the scan command is the same as the behavior
  96.           of  the  ANSI  C  sscanf  procedure except for the following
  97.           differences:
  98.  
  99.           [1]  %p and %n conversion specifiers are not currently  sup-
  100.                ported.
  101.  
  102.           [2]  For %c conversions a single  character  value  is  con-
  103.                verted  to  a decimal string, which is then assigned to
  104.                the corresponding varName; no field width may be speci-
  105.                fied for this conversion.
  106.  
  107.           [3]  The l, h, and L modifiers are ignored;  integer  values
  108.                are  always  converted  as  if  there  were no modifier
  109.                present and real values are always converted as if  the
  110.                l  modifier  were present (i.e. type double is used for
  111.                the internal representation).
  112.  
  113.  
  114.      KEYWORDS
  115.           conversion specifier, parse, scan
  116.